home *** CD-ROM | disk | FTP | other *** search
/ Graphics Plus / Graphics Plus.iso / general / modelers / geomview / sgi.lha / Geomview / man / cat5 / geomview.5 < prev    next >
Text File  |  1993-11-16  |  45KB  |  991 lines
  1.  
  2.  
  3.  
  4. geomview(5)                          geomview(5)
  5.  
  6.  
  7. NAME
  8.        geomview    - geomview command language, version 1.4.1
  9.  
  10. DESCRIPTION
  11.        The  Geomview  language    has the    syntax of lisp -- i.e. an
  12.        expression of the form (f a b ...) means    pass  the  values
  13.        of  a,  b,  ... to the function f.  The present version of
  14.        the language is very limited; it    is  simply  a  "one-pass"
  15.        command    language, rather than a    programming language, but
  16.        this may    change in future versions.
  17.  
  18.        This is the language that geomview understands  for  files
  19.        that it loads as    well as    for communication with other pro-
  20.        grams.  If you want to execute a    command    in  the     language
  21.        interactively,  you can bring up    the "Command" panel which
  22.        lets you    type in    a command; geomview executes the  command
  23.        when you    hit the    return key.  Output from such commands is
  24.        printed to standard output.  Alternately, you  can  invoke
  25.        geomview     as  "geomview -c -" which causes it to    read com-
  26.        mands from standard input.
  27.  
  28.        In the descriptions of the commands below  several  refer-
  29.        ences  are  made     to  "OOGL"  formats.    OOGL  is the data
  30.        description language that  geomview  uses  for  describing
  31.        geometry,  cameras,  appearances, and other basic objects.
  32.        It is described in the "OOGL File Formats" chapter of  the
  33.        manual.    This chapter is    essentially the    same thing as the
  34.        oogl(5) manual page, distributed    with geomview in the file
  35.        man/cat5/oogl.5.
  36.  
  37.        The  geomview  language    command     and  argument    types are
  38.        listed  below.    You  can  see  this  list  while  running
  39.        geomview    by executing the command "(? *)".
  40.  
  41.  
  42.        !           <           =           >
  43.        ?           ??           APPEARANCE      CAM-ID
  44.        CAMERA           GEOM-ID           GEOMETRY           ID
  45.        ND-axes           ND-color           ND-xform           NeXT
  46.        STATEMENT       TRANSFORM       all           ap-override
  47.        backcolor       bbox-color      bbox-draw       camera
  48.        camera-draw     camera-prop     camera-reset    car
  49.        cdr           clock           command           copy
  50.        cull-backface   cursor           cursor-still    cursor-twitch
  51.        delete           dice           dimension       draw
  52.        echo           emodule-clear   emodule-define  emodule-defined
  53.        emodule-isrunning emodule-path     emodule-run     emodule-sort
  54.        emodule-start   emodule-transmit    escale        event-mode
  55.        evert           exit           ezoom           freeze
  56.        geometry           geomview-version    hdefine        help
  57.        hmodel           hsphere-draw    if           inhibit-warning
  58.        interest           lines-closer    load           load-path
  59.        look           look-encompass  look-encompass-size look-recenter
  60.        look-toward     merge           merge-ap           merge-base-ap
  61.  
  62.  
  63.  
  64. Geometry Center         October 29, 1993            1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. geomview(5)                          geomview(5)
  71.  
  72.  
  73.        merge-baseap    morehelp           name-object     new-alien
  74.        new-camera      new-center      new-geometry    new-reset
  75.        normalization   pick           pickable           position
  76.        position-at     position-toward progn           quit
  77.        quote           rawevent           rawpick           read
  78.        real-id           redraw           regtable           rehash-emodule-path
  79.        replace-geometry    rib-display    rib-snapshot    scale
  80.        scene           set-clock       set-conformal-refine set-emodule-path
  81.        set-load-path   set-motionscale setenv           sgi
  82.        shell           sleep-for       sleep-until     snapshot
  83.        soft-shader     space           stereowin       time-interests
  84.        transform       transform-incr  transform-set   ui-center
  85.        ui-emotion-program ui-emotion-run  ui-panel      ui-target
  86.        uninterest      update           update-draw     window
  87.        winenter           write           write-sexpr     xform
  88.        xform-incr      xform-set       zoom           |
  89.  
  90.  
  91.        ! is a synonym for "shell"
  92.        (< EXPR1    EXPR2)
  93.         Returns t if EXPR1 is less than EXPR2.  EXPR1 and EXPR2 should
  94.         be either both integers or floats, or both strings.
  95.        (= EXPR1    EXPR2)
  96.         Returns t if EXPR1 is equal    to EXPR2.  EXPR1 and EXPR2 should
  97.         be either both integers or floats, or both strings.
  98.        (> EXPR1    EXPR2)
  99.         Returns t if EXPR1 is greater than EXPR2.  EXPR1 and EXPR2 should
  100.         be either both integers or floats, or both strings.
  101.        (?  [command])
  102.         Command may    include    "*"s as    wildcards; see also "??"
  103.         One-line command help; lists names only if multiple    commands match.
  104.         ? is a synonym for "help"
  105.        (?? command)  "command" may include "*" wildcards
  106.         Prints more    info than "(? command)".  ?? is    a synonym
  107.         for    "morehelp"
  108.        APPEARANCE is an    OOGL appearance    specification.
  109.        CAM-ID is an ID that refers to a    camera.
  110.        CAMERA is an OOGL camera    specification.
  111.        GEOM-ID is an ID    that refers to a geometry.
  112.        GEOMETRY    is an OOGL geometry specification.
  113.        ID is a string which names a geometry or    camera.     Besides
  114.            those you create, valid ones are:
  115.  
  116.            World, world,
  117.            worldgeom, g0:    the collection of all geom's
  118.            target:             selected target object (cam or geom)
  119.            center:             selected center-of-motion object
  120.            targetcam:         last selected target camera
  121.            targetgeom:         last selected target geom
  122.            focus:             camera where cursor is (or    most
  123.                        recently    was)
  124.            allgeoms:         all geom objects
  125.            allcams:             all cameras
  126.            default,    defaultcam:  prototype;    future cameras inherit
  127.  
  128.  
  129.  
  130. Geometry Center         October 29, 1993            2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. geomview(5)                          geomview(5)
  137.  
  138.  
  139.                        default's settings
  140.  
  141.            The following IDs are used to name coordinate systems,
  142.            e.g. in "pick" and "write" commands:
  143.  
  144.            world, World, etc.:   the world,    within which all other
  145.                        geoms live.
  146.            universe:         the universe, in which the    World, lights
  147.                        and cameras live.  Cameras' world2cam
  148.                        transforms might    better be called
  149.                        universe2cam, etc.
  150.            self:             "this geomview object".  Transform    from
  151.                        an object to "self" is the identity;
  152.                        writing its geometry gives the object
  153.                        itself with no enclosing    transform;
  154.                        picked points appear in the object's
  155.                        coordinates.
  156.            primitive:         (for "pick" only) Picked points appear in
  157.                        the coordinate system of    the
  158.                        lowest-level OOGL primitive.
  159.  
  160.         A name is also an acceptable id.  Given names are made unique
  161.         by appending numbers if necessary (i.e. "foo<2>"). Every geom
  162.         is also named g[n] and every camera    is also    named c[n] ("g0"
  163.         is always the worldgeom): this name    is used    as a prefix to
  164.         keyboard commands and can also be used as a    command    language
  165.         id.     Numbers are reused after an object is deleted.    Both names
  166.         are    shown in the Object browser.
  167.        (ND-axes    CAMID [CLUSTERNAME [Xindex Yindex Zindex]])
  168.         Sets or reads the set of axes in the space of the N-dimensional virtual
  169.         camera CLUSTERNAME which determine the 3-D subspace    seen by    camera CAMID.
  170.         Axes are specified by their    indices, from 0    to N-1 for an N-dimensional
  171.         space.
  172.        (ND-color CAM-ID    [ (((x0    x1 x2 ... xn) v    r g b a      v r g    b a  ... )
  173.         ((x0 ... xn)  v r g    b a  v r g b a ...) ...)] )
  174.        (ND-xform OBJID [ntransform { idim odim    ... }])
  175.         Sets or returns the    N-D transform of the given object.
  176.  
  177.        (NeXT)
  178.         Returns t if running on a NeXT, nil    if not
  179.        STATEMENT represents a function call.  Function calls have
  180.            the form    "( func    arg1 arg2 ... )", where    func is    the name
  181.            of the function and arg1, arg2, ... are the arguments.
  182.        TRANSFORM is an OOGL 4x4    transformation matrix.
  183.        (all geometry)  returns a list of names of all geometry objects.
  184.        (all camera)   returns a    list of    names of all cameras.
  185.        (all emodule defined)  returns a    list of    all defined external modules.
  186.        (all emodule running)  returns a    list of    all running external modules.
  187.        Use e.g.    ``(echo    (all geometry))'' to print such    a list.
  188.        (ap-override [on|off])
  189.         Selects whether appearance controls    should override    objects' own
  190.         settings.  On by default.  With no arguments, returns current setting.
  191.        (backcolor      CAM-ID R    G B)
  192.         Set    the background color of    CAM-ID;    R G B are numbers
  193.  
  194.  
  195.  
  196. Geometry Center         October 29, 1993            3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. geomview(5)                          geomview(5)
  203.  
  204.  
  205.         between 0 and 1.
  206.        (bbox-color     GEOM-ID R G B)
  207.         Set    the bounding-box color of GEOM-ID; R G B are numbers
  208.         between 0 and 1.
  209.        (bbox-draw      GEOM-ID [yes|no])
  210.         Say    whether    GEOM-ID's bounding-box should be drawn;    "yes" if omitted.
  211.        (camera           CAM-ID [CAMERA])
  212.         Specify data for CAM-ID; CAMERA is a string    giving an OOGL
  213.         camera specification.  If no camera    CAM-ID exists,
  214.         it is created; in this case, the second argument is    optional,
  215.         and    if omitted, a default camera is    used.  See also: new-camera.
  216.        (camera-draw    CAM-ID [yes|no])
  217.         Say    whether    or not cameras should be drawn in CAM-ID; "yes"    if omitted.
  218.        (camera-prop { geometry object }      [projective])
  219.         Specify the    object to be shown when    drawing    other cameras.
  220.         By default,    this object is drawn with its origin at    the camera,
  221.         and    with the camera    looking    toward the object's -Z axis.
  222.         With the "projective" keyword, the camera's    viewing    projection is
  223.         also applied to the    object;    this places the    object's Z=-1 and Z=+1 at
  224.         near and far clipping planes, with the viewing area    -1<={X,Y}<=+1.
  225.         Example:  (camera-prop { < cube } projective)
  226.        (camera-reset   CAM-ID)
  227.         Reset CAM-ID to its    default    value.
  228.        (car LIST)
  229.         returns the    first element of LIST.
  230.        (cdr LIST)
  231.         returns the    list obtained by removing the first element of LIST.
  232.        (clock)
  233.         Returns the    current    time, in seconds, as shown by this stream's clock.
  234.         See    also set-clock and sleep-until.
  235.        (command           INFILE [OUTFILE])
  236.         Read commands from INFILE; send corresponding responses
  237.         (e.g. anything written to filename "-") to OUTFILE,    stdout
  238.         by default.
  239.        (copy [ID] [name])
  240.         Copies an object or    camera.     If ID is not specified, it
  241.         is assumed to be targetgeom.  If name is not specified, it
  242.         is assumed to be the same as the name of ID.
  243.        (cull-backface [on|off])
  244.         Select whether back-facing polygons    should be displayed.
  245.         Initially on: all polygons are displayed.  When off, polygons whose
  246.         vertices are arranged clockwise on the screen are hidden.  Useful for
  247.         simulating two-sided surface coloring.
  248.        (cursor CAM-ID  {on|off}    [pbmfile xorigin yorigin])
  249.         Turns the given window's graphics cursor on    or off.
  250.         Optionally sets the    16x16 pixel cursor glyph from the given    file,
  251.         which must be in binary (P4) PBM format.  Can only be applied to
  252.         actual windows, not    e.g. "allcams" or "default".  Sorry.
  253.        (cursor-still [INT])
  254.         Sets the number of microseconds for    which the cursor must not
  255.         move to register as    holding    still.    If INT is not specified,
  256.         the    value will be reset to the default.
  257.        (cursor-twitch [INT])
  258.         Sets the distance which the    cursor must not    move (in x or
  259.  
  260.  
  261.  
  262. Geometry Center         October 29, 1993            4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. geomview(5)                          geomview(5)
  269.  
  270.  
  271.         y) to register as holding still.  If INT is    not specified,
  272.         the    value will be reset to the default.
  273.        (delete           ID)
  274.         Delete object or camera ID.
  275.        (dice           GEOM-ID N)
  276.         Dice any Bezier patches within GEOM-ID into    NxN meshes; default 10.
  277.        (dimension [N])
  278.         Sets or reads the space dimension for N-dimensional    viewing.
  279.         (Since calculations    are done using homogeneous coordinates,
  280.         this means matrices    are (N+1)x(N+1).)
  281.         With no arguments, returns the current dimension, or 0 if
  282.         N-dimensional viewing has not been enabled.
  283.        (draw           CAM-ID)
  284.         Draw the view in CAM-ID, if    it needs redrawing.  See also "redraw".
  285.        (echo          ...)
  286.         Write the given data to the    special    file "-".  Strings are written
  287.         literally; lisp expressions    are evaluated and their    values written.
  288.         If received    from an    external program, "echo" sends to the program's
  289.         input.  Otherwise writes to    geomview's own standard    output
  290.         (typically the terminal).
  291.        (emodule-clear)
  292.         Clears the geomview    application (external module) browser.
  293.        (emodule-define    NAME  SHELL-COMMAND ...)
  294.         Define an external module called NAME, which then appears in the
  295.         external-module browser.  The SHELL-COMMAND    string
  296.         is a UNIX shell command which invokes the module.
  297.         See    emodule-run for    discussion of external modules.
  298.        (emodule-defined    "modulename")
  299.         If the given external-module name is known,    returns    the name of
  300.         the    program    invoked    when it's run as a quoted string; otherwise
  301.         returns nil.  ``(echo (emodule-defined "name"))'' prints the string.
  302.        (emodule-isrunning NAME)
  303.         Returns Lt if the emodule NAME is running, or Lnil
  304.         if it is not running.  NAME    is searched for    in the
  305.         names as they appear in the    browser    and in the shell commands
  306.         used to execute the    external modules (not including    arguements).
  307.        (emodule-path)
  308.         Returns the    current    search path for    external modules.
  309.         Note: to actually see the value returned by    this function
  310.         you    should wrap it in a call to echo: (echo    (emodule-path)).
  311.            See also    set-emodule-path.
  312.        (emodule-run  SHELL-COMMAND ARGS...)
  313.         Runs the given SHELL-COMMAND (a string containing a    UNIX shell
  314.         command) as    an external module.  The module's standard output
  315.         is taken as    geomview commands; responses (written to filename
  316.         "-") are sent to the module's standard input.  The shell
  317.         command is interpreted by /bin/sh, so e.g. I/O redirection may
  318.         be used; a program which prompts the user for input    from the
  319.         terminal could be run with:
  320.           (emodule-run  yourprogram     <&2)
  321.         If not already set,    the environment    variable $MACHTYPE is set
  322.         to the name    of the machine type.  Input and    output
  323.         connections    to geomview are    dropped    when the shell command
  324.         terminates.     Clicking on a running program's module-browser    entry
  325.  
  326.  
  327.  
  328. Geometry Center         October 29, 1993            5
  329.  
  330.  
  331.  
  332.  
  333.  
  334. geomview(5)                          geomview(5)
  335.  
  336.  
  337.         sends the signal SIGHUP to the program.  For this to work, programs
  338.         should avoid running in the    background; those using    FORMS or GL
  339.         should call    foreground() before the    first FORMS or winopen() call.
  340.         See    also emodule-define, emodule-start.
  341.        (emodule-sort)
  342.         Sorts the modules in the application browser alphabetically.
  343.        (emodule-start  NAME)
  344.         Starts the external    module NAME, defined by    emodule-define.
  345.         Equivalent to clicking on the corresponding    module-browser entry.
  346.        (emodule-transmit NAME LIST)
  347.         Places LIST    into external module NAME's standard input.  NAME is
  348.         searched for in the    names of the modules as    they appear in the
  349.         External Modules browser and then in the shell commands used to
  350.         execute the    external modules.  Does    nothing    if modname is not
  351.         running.
  352.        (escale        GEOM-ID    FACTOR)
  353.         Same as scale but multiplies by exp(scale).     Obsolete.
  354.        (event-mode     MODESTRING)
  355.         Set    the mouse event    (motion) mode; MODESTRING should be one    of
  356.         the    strings    that appears in    the motion mode    browser    (including
  357.         the    keyboard shortcut, e.g.    "[r] Rotate").
  358.        (evert           GEOM-ID [yes|no])
  359.         Set    the normal eversion state of GEOM-ID.  If the second argument
  360.         is omitted,    toggle the eversion state.
  361.        (exit)
  362.         Terminates geomview.
  363.        (ezoom           GEOM-ID FACTOR)
  364.         Same as zoom but multiplies    by exp(zoom).  Obsolete.
  365.        (freeze           CAM-ID)
  366.         Freeze CAM-ID; drawing in this camera's window is turned off
  367.         until it is    explicitly redrawn with    "(redraw CAM-ID)", after
  368.         which time drawing resumes as normal.
  369.        (geometry       GEOM-ID [GEOMETRY])
  370.         Specify the    geometry for GEOM-ID.  GEOMETRY    is a string
  371.         giving an OOGL geometry specification.  If no object
  372.         called GEOM-ID exists, it is created; in this case the
  373.         GEOMETRY argument is optional, and if omitted, the new
  374.         object GEOM-ID is given an empty geometry.
  375.        (geomview-version)
  376.         Returns a string representing the version of geomview that is
  377.         running.
  378.        (hdefine     "geometry"|"camera"|"transform"|"window"  name     value)
  379.         Sets the value of a    handle of a given type.
  380.           (hdefine    <type>    <name>    <value>)  is generally equivalent to
  381.           (read <type>  { define <name> <value> })
  382.         except that    the assignment is done when hdefine is executed,
  383.         (possibly not at all if inside a conditional statement),
  384.         while the ``read ... define'' performs assignment as soon as the
  385.         text is read.
  386.  
  387.        (help          [command])
  388.         Command may    include    "*"s as    wildcards; see also "??"
  389.         One-line command help; lists names only if multiple    commands match.
  390.        (hmodel CAMID {virtual|projective|conformal})
  391.  
  392.  
  393.  
  394. Geometry Center         October 29, 1993            6
  395.  
  396.  
  397.  
  398.  
  399.  
  400. geomview(5)                          geomview(5)
  401.  
  402.  
  403.         Set    the model used to display geometry in
  404.         this camera; see also "space".
  405.        (hsphere-draw   CAMID [yes|no])
  406.         Say    whether    to draw    the sphere at infinity in hyperbolic space.
  407.         If the second argument is omitted, "yes" is    assumed.
  408.        (if TEST    EXPR1 [EXPR2])
  409.         Evaluates TEST; if TEST returns a non-nil value, returns the
  410.         value of EXPR1.  If    TEST returns nil, returns the value of
  411.         EXPR2 if EXPR2 is present, otherwise returns nil.
  412.        (inhibit-warning    STRING)
  413.         Inhibit warning inhbits geomview from displaying a
  414.         particular warning message determined by STRING.
  415.         At present there are no warning messages that this
  416.         applies to,    so this    command    is rather useless.
  417.        (interest (COMMAND [args]))
  418.  
  419.         Allows you to express interest in a    command.  When geomview
  420.         executes that command in the future    it will    echo it    to the
  421.         communication pool from which the interest command came.
  422.         COMMAND can    be any command.     Args specify restrictions on the
  423.         values of the arguments; if    args are present in the    interest
  424.         command, geomview will only    echo calls to the command in which
  425.         the    arguments match    those given in the interest command.  Two
  426.         special argument values may    appear in the argument list.  "*"
  427.         matches any    value. "nil" matches any value but supresses the
  428.         reporting of that value; its value is reported as "nil".
  429.  
  430.         The    purpose    of the interest    command    is to allow external
  431.         modules to find out    about things happening inside geomview.
  432.         For    example, a module interested in    knowing    when a geom called
  433.         "foo" is deleted could say "(interest (delete foo))" and would
  434.         receive the    string "(delete    foo)" when foo is deleted.
  435.  
  436.         Picking is a special case of this.    For most modules
  437.         interested in pick events the command "(interest (pick
  438.         world))" is    sufficient.  This causes geomview to send a string
  439.         of the form    "(pick world ...)" every time a    pick event (right
  440.         mouse double click).  See the "pick" command for details.
  441.        (lines-closer   CAM-ID DIST)
  442.         Draw lines (including edges) closer    to the camera than polygons
  443.         by DIST / 10^5  of the Z-buffer range.  DIST = 3.0 by default.
  444.         If DIST is too small, a line lying on a surface may    be
  445.         dotted or invisible, depending on the viewpoint.
  446.         If DIST is too large, lines    may appear in front of surfaces
  447.         that they actually lie behind.  Good values    for DIST vary with
  448.         the    scene, viewpoint, and distance between near and    far clipping
  449.         planes.  This feature is a kludge, but can be helpful.
  450.        (load  filename    [command|geometry|camera)
  451.         Loads the given file into geomview.     The optional second argument
  452.         specifies the type of data it contains, which may be "command"
  453.         (geomview commands), "geometry" (OOGL geometric data), or
  454.         "camera" (OOGL camera definition).    If omitted, attempts to    guess
  455.         about the file's contents.
  456.         Loading geometric data creates a new visible object; loading a camera
  457.  
  458.  
  459.  
  460. Geometry Center         October 29, 1993            7
  461.  
  462.  
  463.  
  464.  
  465.  
  466. geomview(5)                          geomview(5)
  467.  
  468.  
  469.         opens a new    window;    loading    a command file executes    those commands.
  470.  
  471.        (load-path)
  472.         Returns the    current    search path for    command, geometry, etc.    files.
  473.         Note: to actually see the value returned by    this function
  474.         you    should wrap it in a call to echo: (echo    (load-path)).
  475.         See    also set-load-path.
  476.        (look [objectID]    [cameraID])
  477.         Rotates the    named camera to    point toward the center    of the
  478.         bounding box of the    named object (or the origin in hyperbolic or
  479.         spherical space).  In Euclidean space, moves the camera
  480.         forward or backward    until the object appears as large
  481.         as possible    while still being entirely visible.  Equivalent    to
  482.         progn (
  483.          (look-toward [objectID] [cameraID] {center | origin})
  484.          [(look-encompass [objectID] [cameraID])]
  485.         )
  486.         If objectID    is not specified, it is    assumed    to be World.  If
  487.         cameraID is    not specified, it is assumed to    be targetcam.
  488.        (look-encompass [objectID] [cameraID])
  489.         Moves cameraID backwards or    forwards until its field of view
  490.         surrounds objectID.    This routine works only    in Euclidean space.
  491.         If objectID    is not specified, it is    assumed    to be the world.
  492.         If cameraID    is not specified, it is    assumed    to be the targetcam.
  493.         See    also (look-encompass-size).
  494.        (look-encompass-size [view-fraction  clip-ratio    near-margin far-margin])
  495.         Sets/returns parameters used by (look-encompass).
  496.         view-fraction is the portion of the    camera window filled by    the object,
  497.         clip-ratio is the max allowed ratio    of near-to-far clipping    planes.
  498.         The    near clipping plane is 1/near-margin times closer than the near
  499.         edge of the    object,    and the    far clipping plane is far-margin times
  500.         further away.  Returns the list of current values.
  501.         Defaults: .75  100    0.1  4.0
  502.  
  503.        (look-recenter [objectID] [cameraID])
  504.         Translates and rotates the camera so that it is looking in the
  505.         -z direction (in objectID's    coordinate system) at the center of
  506.         objectID's bounding    box (or    the origin of the coordinate system
  507.         in non-Eudlidean space).  In Euclidean space, the camera is    also
  508.         moved as close as possible to the object while allowing the
  509.         entire object to be    visible.  Also makes sure that the y-axes of
  510.         objectID and cameraID are parallel.
  511.        (look-toward [objectID] [cameraID] [origin | center])
  512.         Rotates the    named camera to    point toward the origin    of the
  513.         object's coordinate    system,    or the center of the object's
  514.         bounding box (in non-Euclidean space, the origin will be used
  515.         automatically).  Default objectID is the world, default camera
  516.         is targetcam, default location to point towards is the center
  517.         of the bounding box.
  518.        (merge           {window|camera} CAM-ID  { WINDOW    or CAMERA ... }    )
  519.         Modify the given window or camera, changing    just those properties
  520.         specified in the last argument.  E.g.
  521.          (merge    camera "Camera"    { far 20 })
  522.         sets Camera's far clipping plane to    20 while leaving
  523.  
  524.  
  525.  
  526. Geometry Center         October 29, 1993            8
  527.  
  528.  
  529.  
  530.  
  531.  
  532. geomview(5)                          geomview(5)
  533.  
  534.  
  535.         other attributes untouched.
  536.        (merge-ap       GEOM-ID APPEARANCE)
  537.         Merge in some appearance characteristics to    GEOM-ID.
  538.         Appearance parameters include surface and line color, shading
  539.         style, line    width, and lighting.
  540.        merge-base-ap is    a synonym for merge-baseap.
  541.        (merge-baseap   APPEARANCE)
  542.         Merge in some appearance characteristics to    the base default
  543.         appearance (applied    to every geom before its own apperance).
  544.         Lighting is    typically included in the base appearance.
  545.        (morehelp    command)  "command"    may include "*"    wildcards
  546.         Prints more    info than "(help command)"
  547.        (name-object    ID NAME)
  548.         Assign a new NAME (a string) to ID.     A number is appended if
  549.         that name is in use    (for example, "foo" -> "foo<2>").  The new
  550.         name, possibly with    number appended, may be    used as    object's
  551.         id thereafter.
  552.        (new-alien      name [GEOMETRY])
  553.         Create a new alien (geom not in the    world) with the    given name
  554.         (a string).     GEOMETRY is a string giving an    OOGL geometry
  555.         specification.  If GEOMETRY    is omitted, the    new alien
  556.         is given an    empty geometry.     If an object with that    name
  557.         already exists, the    new alien is given a unique name.  The
  558.         light beams    that are used to move around the lights    are an
  559.         example of aliens. They're drawn but are not controllable the
  560.         way    ordinary objects are: they don't appear    in the object
  561.         browser and    the user can't move them with the normal motion
  562.         modes.
  563.        (new-camera     name [CAMERA])
  564.         Create a new camera    with the given name (a string).     If a
  565.         camera with    that name already exists, the new object is given
  566.         a unique name.  If CAMERA is omitted a default camera is used.
  567.        (new-center [id])
  568.         Stop id, then set id's transform to    the identity.  Default id
  569.         is target.    Also, if the id    is a camera, calls
  570.         (look-recenter World id).  The main    function of the    call to
  571.         (look-recenter) is to place    the camera so that it is pointing
  572.         parallel to    the z axis toward the center of    the world.
  573.        (new-geometry   name [GEOMETRY])
  574.         Create a new geom with the given name (a string).  GEOMETRY    is
  575.         a string giving an OOGL geometry specification.  If
  576.         GEOMETRY is    omitted, the new object    is given an empty geometry.
  577.         If an object with that name    already    exists,    the new    object is
  578.         given a unique name.
  579.        (new-reset)
  580.         Equivalent to (progn (new-center ALLGEOMS)(new-center ALLCAMS))
  581.        (normalization  GEOM-ID {each|none|all|keep})
  582.         Set    the normalization status of GEOM-ID.
  583.         "none" suppresses all normalization.
  584.         "each" normalizes the object's bounding box    to fit into the    unit
  585.            sphere, with the    center of its bounding box translated
  586.            to the origin.  The box is scaled such that its long diagonal,
  587.            sqrt((xmax-xmin)^2 + (ymax-ymin)^2 + (zmax-zmin)^2), is 2.
  588.         "all" resembles "each", except when    an object is changing
  589.  
  590.  
  591.  
  592. Geometry Center         October 29, 1993            9
  593.  
  594.  
  595.  
  596.  
  597.  
  598. geomview(5)                          geomview(5)
  599.  
  600.  
  601.            (e.g. when its geometry is being    changed    by an external program).
  602.  
  603.            Then, "each" tightly fits the bounding box around the
  604.            object whenever it changes and normalizes accordingly,
  605.            while "all" normalizes the union    of all variants    of the object
  606.            and normalizes accordingly.
  607.  
  608.         "keep" leaves the current normalization transform unchanged
  609.         when the object changes.  It may be    useful to apply    "each" or
  610.         "all" normalization    apply to the first version of a    changing
  611.         object to bring it in view,    then switch to "keep"
  612.        (pick COORDSYS GEOMID G V E F P VI EI FI)
  613.         The    pick command is    executed internally in response    to pick
  614.         events (right mouse    double click).
  615.  
  616.         COORDSYS = coordinate system in which coordinates of the following
  617.         arguments are specified.   This    can be:
  618.          world:    world coord sys
  619.          self:    coord sys of the picked    geom (GEOMID)
  620.          primitive: coord sys of the actual primitive within
  621.              the picked    geom where the pick occurred.
  622.         GEOMID = id    of picked geom
  623.         G =    picked point (actual intersection of pick ray with object)
  624.         V =    picked vertex, if any
  625.         E =    picked edge, if    any
  626.         F =    picked face
  627.         P =    path to    picked primitive [0 or more]
  628.         VI = index of picked vertex    in primitive
  629.         EI = list of indices of endpoints of picked    edge, if any
  630.         FI = index of picked face
  631.  
  632.         External modules can find out about    pick events by registering
  633.         interest in    calls to "pick"    via the    "interest" command.
  634.        (pickable       GEOM-ID {yes|no})
  635.         Say    whether    or not GEOM-ID is included in the pool of objects
  636.         that could be returned from    the pick command.
  637.        (position       objectID    otherID)
  638.         Set    the transform of objectID to that of otherID.
  639.        (position-at    objectID    otherID    [center    | origin])
  640.         Translate objectID to the center of    the bounding box or the
  641.         origin of the coordinate system of otherID (parallel translation).
  642.         Default is center.
  643.        (position-toward    objectID otherID [center | origin])
  644.         Rotate objectID so that the    center of the bounding box
  645.         or the origin of the coordinate system of the otherID
  646.         lies on the    positive z-axis    of the first object.  Default is
  647.         the    center of the bounding box.
  648.        (progn STATEMENT    [ ... ])
  649.         evaluates each STATEMENT in    order and returns the value of the
  650.         last one.  Use progn to group a collection of commands together,
  651.         forcing them to be treated as a single command.
  652.        quit is a synonym for "exit"
  653.        (quote EXPR)
  654.         returns the    symbolic lisp expression EXPR without evaluating it.
  655.  
  656.  
  657.  
  658. Geometry Center         October 29, 1993               10
  659.  
  660.  
  661.  
  662.  
  663.  
  664. geomview(5)                          geomview(5)
  665.  
  666.  
  667.        (rawevent       dev val x y t)
  668.         Enter the specified    raw event into the event queue.     The
  669.         arguments directly specify the members of the event    structure
  670.         used internally by geomview.  This is the lowest level event
  671.         handler and    is not intended    for general use.
  672.        (rawpick    CAMID X    Y)
  673.         Process a pick event in camera CAMID at location (X,Y) given in
  674.         integer pixel coordinates.    This is    a low-level procedure not
  675.         intended for external use.
  676.        (read {geometry|camera|transform|command} {GEOMETRY or CAMERA or    ...})
  677.         Read and interpret the text    in ... as containing the
  678.         given type of data.     Useful    for defining objects using OOGL
  679.         reference syntax, e.g.
  680.  
  681.           (geometry     thing { INST  transform : T    geom : fred })
  682.           (read  geometry  { define    fred QUAD 1 0 0     0 1 0    0 0 1  1 0 0 })
  683.           (read  transform { define    T <myfile})
  684.        (real-id    ID)
  685.         Returns a string canonically identifying the given ID,
  686.         or "nil" if    the object does    not exist.  Examples:
  687.          (if (real-id fred)    (delete    fred))
  688.         deletes "fred" if it exists    but reports no error if    it doesn't, and
  689.          (if (= (real-id targetgeom) (real-id World)) () (delete targetgeom))
  690.         deletes "targetgeom" if it is different from the World.
  691.  
  692.        (redraw           CAM-ID)
  693.         States that    the view in CAM-ID should be redrawn on    the
  694.         next pass through the main loop or the next    invocation of "draw".
  695.        (regtable) --- shows the    registry table
  696.        (rehash-emodule-path)
  697.         Rebuilds the application (external module) browser by reading
  698.         all    .geomview-* files in all directories on    the emodule-path.
  699.         Primarily intended for internal use; any applications defined
  700.         by (emodule-define ...) commands outside of    the .geomview-*
  701.         files on the emodule-path will be lost.  Does not sort the
  702.         entries in the brower; see (emodule-sort) for that.
  703.        (replace-geometry GEOM-ID PART-SPECIFICATION GEOMETRY)
  704.         Replace a part of the geometry for GEOM-ID.
  705.        (rib-display    [frame|tiff] FILEPREFIX)
  706.         Set    Renderman display to framebuffer (popup    screen window) or a
  707.         TIFF format    disk file. FILEPREFIX is used to construct
  708.         names of the form "prefixNNNN.suffix". (i.e. foo0000.rib)
  709.         The    number is incremented on every call to "rib-snapshot" and
  710.         reset to 0000 when "rib-display" is    called.    TIFF files are given
  711.         the    same prefix and    number as the RIB file (i.e. foo0004.rib
  712.         generates foo0004.tiff). The default FILEPREFIX is "geom" and
  713.         the    default    format is TIFF.    (Note that geomview just generates a
  714.         RIB    file, which must then be rendered.)
  715.        (rib-snapshot   CAM-ID  [filename])
  716.         Write Renderman snapshot (in RIB format) of    CAM-ID to <filename>.
  717.         If no filename specified, see "rib-display"    for explanation    of
  718.         the    filename used.
  719.        (scale           GEOM-ID FACTOR [FACTORY FACTORZ])
  720.         Scale GEOM-ID, multiplying its size    by FACTOR.  The    factors
  721.  
  722.  
  723.  
  724. Geometry Center         October 29, 1993               11
  725.  
  726.  
  727.  
  728.  
  729.  
  730. geomview(5)                          geomview(5)
  731.  
  732.  
  733.         should be positive numbers.     If FACTORY and    FACTORZ    are
  734.         present and    non-zero, the object is    scaled by FACTOR in x, by
  735.         FACTORY in y, and by FACTORZ in z.    If only    FACTOR is present,
  736.         the    object is scaled by FACTOR in x, y, and    z.  Scaling only
  737.         really makes sense in Euclidean space.  Mouse-driven scaling in
  738.         other spaces is not    allowed;  the scale command may    be issued
  739.         in other spaces but    should be used with caution because it may
  740.         cause the data to extend beyond the    limits of the space.
  741.        (scene           CAM-ID [GEOMETRY])
  742.         Make CAM-ID    look at    GEOMETRY instead of at the universe.
  743.        (set-clock TIME)
  744.         Adjusts the    clock for this command stream to read TIME (in seconds)
  745.         as of the moment the command is received.  See also    sleep-until, clock.
  746.        (set-conformal-refine CMX [N [SHOWEDGES]])
  747.         Sets the parameters    for the    refinement algorithm used in drawing
  748.         in the conformal model.  CMX is the    cosine of the maximum angle
  749.         an edge can    bend before it is refined.  Its    value should be    between
  750.         -1 and 1; the default is 0.95; decreasing its value    will cause less
  751.         refinement.     N is the maximum number of iterations of refining;
  752.         the    default    is 6.  SHOWEDGES, which    should be "no" or "yes",
  753.         determines whether interior    edges in the refinement    are drawn.
  754.        (set-emodule-path      (PATH1 ... PATHN))
  755.         Sets the search path for external modules.    The PATHi should
  756.         be pathnames of directories    containing, for    each module, the
  757.         module's executable    file and a .geomview-<modulename> file
  758.         which contains an (emodule-define ...) command for that
  759.         module.  This command implicitly calls (rehash-emodule-path)
  760.         to rebuild the application brower from the new path    setting.
  761.        (set-load-path       (PATH1 ... PATHN))
  762.         Sets search    path for command, geometry, etc. files.     The PATHi
  763.         are    strings    giving the pathnames of    directories
  764.         to be searched.
  765.        (set-motionscale    X)
  766.         Set    the motion scale factor    to X (default value 0.5).  These
  767.         commands scale their motion    by an amount which depends on the
  768.         distance from the frame to the center and on the size of the
  769.         frame.  Specifically, they scale by
  770.             dist + scaleof(frame) * motionscale
  771.         where dist is the distance from the    center to the frame and
  772.         motionscale    is the motion scale factor set by this function.
  773.         Scaleof(frame) measures the    size of    the frame object.
  774.        (setenv    name string)  sets the environment variable ``name'' to    the value
  775.        ``string''; the name is visible to geomview (as in pathnames containing $name)
  776.        and to processes    it creates, e.g. external modules.
  777.        (sgi)
  778.         Returns t if running on an sgi machine, nil    if not
  779.        (shell          SHELL-COMMAND)
  780.         Execute the    given UNIX SHELL-COMMAND using /bin/sh.     Geomview
  781.         waits for it to complete and will be unresponsive until it does.
  782.        (sleep_for  TIME)
  783.         Suspend reading commands from this stream for TIME seconds.
  784.         Commands already read will still be    executed; ``sleep-for''    inside
  785.         ``progn'' won't delay execution of the rest    of the progn's contents.
  786.        (sleep-until TIME)
  787.  
  788.  
  789.  
  790. Geometry Center         October 29, 1993               12
  791.  
  792.  
  793.  
  794.  
  795.  
  796. geomview(5)                          geomview(5)
  797.  
  798.  
  799.         Suspend reading commands from this stream until TIME (in seconds).
  800.         Commands already read will still be    executed; ``sleep-until'' inside
  801.         ``progn'' won't delay execution of the rest    of the progn's contents.
  802.         Time is measured according to this stream's    clock, as set by
  803.         ``set-clock''; if never set, the first sleep-until sets it to 0
  804.         (so    initially (sleep-until TIME) is    the same as (sleep-for TIME)).
  805.         Returns the    number of seconds until    TIME.
  806.        (snapshot       CAM-ID      FILENAME)
  807.         Save a snapshot of CAM-ID in IRIS rgb image    format in file FILENAME
  808.         (a string).      The window is    popped above all other windows and
  809.         redrawn before taking the snapshot.
  810.        (soft-shader  CAM-ID  {on|off|toggle})
  811.         Select whether to use software or hardware shading in that camera.
  812.        (space {euclidean|hyperbolic|spherical})
  813.         Set    the space associated with the world.
  814.        (stereowin     CAM-ID  [no|horizontal|vertical|colored] [gapsize])
  815.         Configure CAM-ID as    a stereo window.
  816.         no:    entire window is a single pane,    stereo disabled
  817.         horizontal:    split left/right: left is stereo eye#0,    right is #1.
  818.         vertical: split top/bottom:    bottom is eye#0, top is    #1.
  819.         colored: panes overlap, red    is stereo eye#0, cyan is #1.
  820.         A gap of "gapsize" pixels is left between subwindows;
  821.         if omitted,    subwindows are adjacent.
  822.         If both layout and gapsize are omitted, e.g. (stereowin CAM-ID),
  823.         returns current settings as    a ``(stereowin ...)'' command list.
  824.         This command doesn't set stereo projection;    use ``merge camera'' or
  825.         ``camera'' to set the stereyes transforms, and ``merge window'' or
  826.         ``window'' to set the pixel    aspect ratio & window position if needed.
  827.        (time-interests deltatime initial prefix    [suffix])
  828.         Indicates that all interest-related    messages, when separated by at
  829.         least "deltatime" seconds of real time, should be preceded by
  830.         the    string ``prefix'' and followed by ``suffix''; the first    message
  831.         is preceded    by ``initial''.     All three are printf format strings,
  832.         whose argument is the current clock    time (in seconds) on that stream.
  833.         A "deltatime" of zero timestamps every message.  Typical usage:
  834.         (time-interests .1 "(set-clock %g)"    "(sleep-until %g)")  or
  835.         (time-interests .1 "(set-clock %g)"
  836.          "(sleep-until %g) (progn (set-clock %g)" ")")      or
  837.         (time-interests .1 "(set-clock %g)"
  838.              "(if (> 0 (sleep-until    %g)) ("    "))".
  839.        (transform      objectID    centerID frameID [rotate|translate|translate-scaled] x y z)
  840.         Apply a motion (rotation or    translation) to    object "objectID"; that
  841.         is,    construct and concatenate a transformation matrix with
  842.         objectID's transform  The 3    IDs involved are the object
  843.         that moves,    the center of motion, and the frame of reference
  844.         in which to    apply the motion.  The center is easiest understood
  845.         for    rotations: if centerID is the same as objectID then it will
  846.         spin around    its own    axes; otherwise    the moving object will orbit
  847.         the    center object.    Normally frameID, in whose coordinate system
  848.         the    (mouse)    motions    are interpreted, is "focus", the current camera.
  849.         Translations can be    scaled proportional to the
  850.         distance between the target    and the    center.    Support    for
  851.         spherical and hyperbolic as    well as    Euclidean space    is
  852.         built-in: use the "space" command to change    spaces.     With type
  853.  
  854.  
  855.  
  856. Geometry Center         October 29, 1993               13
  857.  
  858.  
  859.  
  860.  
  861.  
  862. geomview(5)                          geomview(5)
  863.  
  864.  
  865.         "rotate" x,    y, and z are floats specifying angles in radians.
  866.         For    types "translate" and "translate-scaled" x, y, and z are
  867.         floats specifying distances    in the coordinate system of the
  868.         center object.
  869.        (transform-incr    objectID centerID frameID [rotate|translate|translate-scaled] x    y z [dt])
  870.         Apply continuing motion: construct a transformation    matrix and
  871.         concatenate    it with    the current transform of objectID every
  872.         refresh (sets objectID's incremental transform). Same syntax
  873.         as transform.  If optional "dt" argument is    present,
  874.         the    object is moved    at each    time step such that its    average    motion
  875.         equals one instance    of the motion per "dt" seconds.     E.g.
  876.           (transform-incr  World World World  rotate  360 0    0  10.0)
  877.         rotates the    World about its    X axis at 360 degrees every 10 seconds.
  878.  
  879.        (transform-set objectID centerID    frameID    [rotate|translate|translate-scaled] x y    z)
  880.         Set    objectID's transform to    the constructed    transform.
  881.         Same syntax    as transform.
  882.        (ui-center      ID)
  883.         Set    the center for user interface (i.e. mouse) controlled
  884.         motions to object ID.
  885.        ui-emotion-program is an    obsolete command.
  886.         Use    its new    eqivalent "emodule-define" instead.
  887.        ui-emotion-run is an obsolete command.
  888.         Use    its new    eqivalent "emodule_start" instead.
  889.        (ui-panel       PANELNAME  {on|off} [ WINDOW ] )
  890.         Do or don't    display    the given user-interface panel.
  891.         Case is ignored in panel names.  Current PANELNAMEs    are:
  892.          geomview  main    panel
  893.          tools        motion controls
  894.          appearance    appearance controls
  895.          cameras    camera controls
  896.          lighting  lighting controls
  897.          obscure    obscure    controls
  898.          materials material properties controls
  899.          command    command    entry box
  900.          credits    geomview credits
  901.         By default,    the "geomview" and "tools" panels appear when
  902.         geomview starts.  If the optional Window is    supplied, a
  903.         "position" clause (e.g. (ui-panel obscure on { position xmin
  904.         xmax ymin ymax }) sets the panel's default position.  (Only
  905.         xmin and ymin values are actually used.)  A    present    but empty
  906.         Window, e.g.  "(ui-panel obscure on    {})" causes interactive
  907.         positioning.
  908.        (ui-target      ID [yes|no])
  909.         Set    the target of user actions (the    selected line of the
  910.         target object browser) to ID.  The second argument specifies
  911.         whether to make ID the current object regardless of    its type.
  912.         If "no", then ID becomes the current object    of its type
  913.         (geom or camera).  The default is "yes".  This command may
  914.         result in a    change of motion modes based on    target choice.
  915.        (uninterest (COMMAND [args]))
  916.         Undoes the effect of an "interest" command.     (COMMAND [args]) must
  917.         be identical to those used in the "interest" command.
  918.        (update [timestep_in_seconds])
  919.  
  920.  
  921.  
  922. Geometry Center         October 29, 1993               14
  923.  
  924.  
  925.  
  926.  
  927.  
  928. geomview(5)                          geomview(5)
  929.  
  930.  
  931.         Apply each incremental motion once.     Uses timestep if it's present and
  932.         nonzero; otherwise motions are proportional    to elapsed real    time.
  933.        (update-draw    CAM-ID  [timestep_in_seconds])
  934.         Apply each incremental motion once and then    draw CAM-ID.
  935.         Applies "timestep" seconds'    worth of motion, or uses elapsed real
  936.         time if "timestep" is absent or zero.
  937.        (window           CAM-ID  WINDOW)
  938.         Specify attributes for the window of CAM-ID, e.g. its size
  939.         or initial position, in the    OOGL Window syntax.
  940.         The    special    CAM-ID "default" specifies
  941.         properties of future windows (created by "camera" or
  942.         "new-camera").
  943.        (winenter       CAM-ID)
  944.         Tell geomview that the mouse cursor    is in the window
  945.         of CAM-ID.    This function is for development purposes
  946.         and    is not intended    for general use.
  947.        (write {command,geometry,camera,transform,window} FILENAME [ID|(ID ...)]    [self|world|universe|otherID])
  948.         write description of ID in given format to FILENAME.  Last
  949.         parameter chooses coordinate system    for geometry & transform:
  950.         self: just the object, no transformation or    appearance (geometry only)
  951.         world: the object as positioned within the World.
  952.         universe: object's position    in universal coordinates;
  953.         includes Worldtransform
  954.         other ID: the object transformed to    otherID's coordinate system.
  955.  
  956.         A filename of "-" is a special case: data are written to the
  957.         stream from    which the 'write' command was read.  For external
  958.         modules, the data are sent to the module's standard    input.
  959.         For    commands not read from an external program, "-"    means
  960.         geomview's standard    output.     (See also the "command"
  961.         command.)
  962.  
  963.         The    ID can either be a single id or    a parenthesized    list of
  964.         ids, like "g0" or "(g2 g1 dodec.off)".
  965.        (write-sexpr    FILENAME LISPOBJECT)
  966.         Writes the given LISPOBJECT    to FILENAME. This function is intended
  967.         for    internal debugging use only.
  968.        (xform           ID TRANSFORM)
  969.         Concatenate    TRANSFORM with the current transform of    the object
  970.         (apply TRANSFORM to    object ID).
  971.        (xform-incr     ID TRANSFORM)
  972.         Apply continual motion: concatenate    TRANSFORM with the current
  973.         transform of the object every refresh (set object ID's
  974.         incremental    transform to TRANSFORM).
  975.        (xform-set      ID TRANSFORM)
  976.         Overwrite the current object transform with    TRANSFORM (set
  977.         object ID's    transform to TRANSFORM).
  978.        (zoom           CAM-ID FACTOR)
  979.         Zoom CAM-ID, multiplying its field of view by FACTOR.
  980.         FACTOR should be a positive    number.
  981.        | is a synonym for "emodule-run"
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988. Geometry Center         October 29, 1993               15
  989.  
  990.  
  991.